FishMarket 1.0/FishMarket v1.0.iso/fishies/551-575/disk_573/multiplayer/player.doc

Text File | 1992-05-06 | 41KB | 946 lines

                MultiPlayer
                   Version 1.11
               Copyright (C) 1991 Bryan    Ford
                All    Rights Reserved


                   Introduction
                   ~~~~~~~~~~~~

    MultiPlayer    is a program to    play Amiga music modules, such as
Soundtracker and MED modules. (This program has    no relation to Multi_Player
by Thomas Landspurg which I just recently found    out about.) Before you get
disgusted with Yet Another Module Player, I would encourage you    to read
through    this document, or at least take    MultiPlayer for    a test drive.  You
will find that MultiPlayer has almost all the important    features you've
seen on    other players, plus some you haven't seen before.

    One    of the goals of    MultiPlayer is to be as    system-friendly    as
possible.  It multitasks well, it doesn't interfere with high-priority
interrupts such    as serial port interrupts, and it properly allocates audio
channels so that the music doesn't conflict with other programs.  It is
fully functional on Kickstart 2.0 and 1.3 (although the    control    panels look
nicer on 2.0), and isn't prone to "lose" notes on fast processors like
most other players are.

    Another goal of MultiPlayer    was to support a very diverse array of
music formats.    MultiPlayer currently supports over fifteen different
common module formats, plus some special ones.    See 'Supported Formats'
near the end of    this document for a list of the    module types MultiPlayer
can play.

    The    unregistered version of    MultiPlayer is freely redistributable as
long as    it and its documentation is not    modified in any    way, and the files
listed below are distributed with it.  (See the    end of this file for
details    about registering MultiPlayer.)    You may    not charge more    for
distributing it    than a small fee to cover the disk copying expenses.  The
MultiPlayer version 1.11 distribution must contain the following files:

    Player.doc            MultiPlayer documentation (this    file)
    Player                MultiPlayer itself
    Player.info            Icon for MultiPlayer

    Programmers/Formats.doc        Specification of GMOD module format
    Programmers/GMOD.i        Include    file to    help with GMOD's
    Programmers/DW_GMOD.asm        Example    GMOD header
    Programmers/DW_Convert.c    Example    program    to write GMOD files
    Programmers/DW_Convert        Executable version of same
    Programmers/LMKFile        SAS/C makefile for DW_Convert

    ChipMunch
    ChipMunch/ChipMunch        Useful Utility (for >512K chip RAM)
    ChipMunch/ChipMunch.info    Icon for ChipMunch
    ChipMunch/ChipMunch.doc        Documentation for ChipMunch
    ChipMunch/src/chipmunch.c    SAS/C source for ChipMunch
    ChipMunch/src/makescript    MakeScript for ChipMunch
    ChipMunch/src/sascopts        SAS/C options



                   General Usage

    To start MultiPlayer, just type 'player' from the CLI or click on the
icon from the Workbench    and it will present the    ASL or ARP filerequester to
select a module    from, depending    on which version of the    operating system
you are    using.    (If you    are running 1.3, you must have the arp.library
version    39 or higher installed to get the file requester - if you don't,
you won't be able to load modules from the window.) Under 2.0, you can
select multiple    modules    at a time (as many as you want).  Under    1.3, you
will have to select them one at    a time (although you can still build
programs).  If you run MultiPlayer from    the CLI, it automatically detaches
itself,    so there is no need to Run it.    You can    also start modules playing
immediately when MultiPlayer starts up - see the section on 'Startup
Options' for more information on starting MultiPlayer.

    While MultiPlayer is running there is normally a small window in the
title bar displaying the name of the module that is currently playing (or
just "MultiPlayer" if nothing is loaded).  You can click the close gadget
to stop    the music and terminate    MultiPlayer.  If you are running Kickstart
2.0, the MultiPlayer window will have a    zoom gadget near its right end.     If
you click it, you will see a control panel that    allows you to load
different modules and gives access to some of MultiPlayer's more advanced
features.  Since 1.3 doesn't know about zoom gadgets, you can get the
control    panel under 1.3    by pressing the    right mouse button while the
MultiPlayer window is active.

    If you have    the xpkmaster.library (a freeware compression "supervisor"
standard by Dominik Mueller, Christian Schneider, and myself) installed    in
your system, MultiPlayer can automatically unpack modules that are packed
using any format it can    understand.  (This includes PowerPacker    format,    if
you have the powerpacker.library installed as well.)

    You    may be skeptical about keeping a 50K program resident in memory.
Never fear - thanks to a custom    memory management and overlay system,
MultiPlayer uses only the memory it needs to do    its job.  All of the module
players    are loaded only    when needed, and any players not currently in use
are unloaded on    demand if the system runs out of memory.  The parts of the
program    used to    control    MultiPlayer's various windows are also only loaded
on when    they are needed    (when the windows are open) and    are freed as
necessary.

    For    all you    hackers    (used in the positive meaning) that like to rip    out
every form of music imaginable,    when you come across some obscure module
format that nothing understands, don't despair.  There are several special
formats    built into MultiPlayer that you    can use    to easily interface it to
any kind of module.  All you need is the module, some player code for the
module (if the module doesn't already have embedded player code), and a
little assembly    language programming.  Details on all three formats are    in
the separate file 'Formats.doc'.  If you are the author    of a music composer
program, you should also read this document and    consider supporting the
GMOD embedded-player module format in your program.



                   Control Panel
                   ~~~~~~~~~~~~~

    The    main MultiPlayer window    normally sits quietly in the title bar.
However, if you    click the zoom gadget under 2.0    or click the right mouse
button under 1.3, it will become a small control panel.     Under 2.0, if
you have a 3-button mouse, the middle button will act the same as the
zoom gadget.  This panel displays a few    pieces of information about the
module currently playing, and has some buttons you can use to control
MultiPlayer.

    When running under Workbench 2.0, the MultiPlayer control panel is an
AppWindow, so you can play modules by simply dropping their icons into the
MultiPlayer window.  When you do, the new module (or several modules, if
you extended-select them) replaces the current program,    and MultiPlayer
starts playing the first module    immediately.  This works basically like
selecting modules with the New button.

Module box

    This box displays the filename of the module currently loaded
(essentially the same as what is displayed in the title    bar).  Any 'mod.'
prefixes for Soundtracker/Noisetracker modules will not    be displayed.

Type box

    Displays the type of the loaded module (as MultiPlayer sees    it).
Simple enough?

Author box

    Displays the name of the person who    wrote this module, if MultiPlayer
can glean this information from    the module.  Most current module formats
don't have direct facilities for identifying the author - in this case, the
box will just display 'Unknown'.  Soundtracker/Noisetracker modules often
have author names embedded in the instrument list - in this case,
MultiPlayer will try to    make a good guess by searching for keywords such as
'by' in    the instrument list.  (If it screws up for some    reason,    you can
always TYPE the    module HEX to find out for sure.) MED modules have somewhat
better support,    but they still don't have a convenient 'author' field -
just a catch-all 'annotation' field, which MultiPlayer processes much the
same way as with Soundtracker modules.    GMOD modules are the only types    I
know of    that directly support author identification, but they are at the
moment few and far between.  (Let's get with it, OK?  Don't all    you
wonderful musicians want to be recognized?)

Song gadget

    This gadget    serves two purposes.  First, it    displays the name of the
currently loaded module    or song    as recorded in the module itself.  For
example, with Soundtracker/Noisetracker    modules    this gadget will display
the song name as recorded in the first 20 bytes    of the file.  Many module
formats    don't have built-in name fields - in this case, the box will just
display    'Unknown.'

    For    most types of modules, which support only one song per module, this
gadget will serve no purpose other than    displaying the song name - clicking
on it will do nothing.    However, some module formats such as (GMODs) allow
several    independent songs to be    contained in a single module (for example,
to save    memory by using    the same instruments on    several    songs).     In that
case, this gadget will cycle through the available songs in the    module.
You can    also change songs using    the left and right arrow keys.

New button

    This button    is equivalent to clicking the right mouse button while the
main MultiPlayer window    is active.  It displays    the file requester and lets
you select any number of modules.  The new list    of modules replaces the
current    program, if there was one.  The    first module in    the list (or a
random module, if you have selected random playing) will be started.  The
program    will be    created    with the order in which    the modules were displayed
in the file requester.    (At least this is how the current 2.0 file
requester works    - it may change.)

Play button

    Starts or continues    playing    a module that was previously stopped but
not unloaded.  If the module type supports the continue    feature, the module
will continue playing where it left off.  Otherwise it will start again
from the beginning.

Stop button

    Stops the current module without unloading it.  Audio channels and
interrupts are freed while a module is stopped,    so you don't have to exit
MultiPlayer completely if you want to run some other program that needs    the
audio hardware.     If the    module type supports restart, you can restart it
where it left off by pressing the Play button.

Eject button

    Stops and unloads the currently loaded module, and frees all memory    and
other resources    that the module    was using.

Next button

    Loads and plays the    next module in the current program list.  If you
have selected random play, this    button simply loads another module in the
list, at random.  This is the same as pressing the down    arrow key in the
MultiPlayer window.

Prev button

    Loads and plays the    previous module    in the program list.  If you have
selected random    play, this button does basically the same thing    as the Next
button - picks another module at random.  This button does the same thing
as pressing the    up arrow key in    the MultiPlayer    window.

Program    button

    Opens the Program window, described    below.    Under 2.0, you can
also do    this by    clicking the right mouse button    while the main MultiPlayer
window is active.

Prefs button

    Opens MultiPlayer's Preferences window, described later.



                  Program Window
                  ~~~~~~~~~~~~~~

    The    program    window displays    a list of all the modules in the current
module 'program'. You can select modules from the list to load and play
immediately.  You can also build and rearrange your program using this
window.     (Under    1.3, this window provides the only way to build    programs
from within MultiPlayer, since the ARP file requester doesn't support
multiselect.) You get this window by pressing the 'Program' button on the
main window's control panel, or by pressing the Help key in the MultiPlayer
window,    or, under 2.0, by simply clicking the right mouse button while the
main window is active.    Note that this window doesn't cause the main
control    panel to "freeze" - you    can still watch    and use    it while this
window is open.     In fact, all of MultiPlayer's windows (even the file
requester) are asynchronous.

    If sequenced play is selected (the default), when one module is
finished, the next lower one on    the list is loaded and played.    (This only
applies    on modules that    can detect repeat - most do, but on those that
don't, the module will just play forever until you explicitly tell
MultiPlayer to go to the next module.) With random play, a different module
will be    randomly chosen.  There    is no limit to the number of modules you
can have in a program, and modules in the program can be located in many
different directories -    MultiPlayer will remember the location of each
module.

    When running under Workbench 2.0, the Program window is an AppWindow,
so you can add modules by simply dropping their    icons into this    window.
This window works slightly differently from the    main Multiplayer window,
however.  When you drop    icons into this    window,    the behavior is    the same as
if you had selected the    modules    with the 'Add' button:    The new    modules    are
added to the end of the    current    program    list, and whatever is currently
playing    remains    unaffected.

    Besides the    module listing,    this window contains several buttons that
allow you to manipulate    the module list.  These    are described below:

Top, Up, Down, and Bot buttons

    These buttons allow    you to rearrange the modules in    the program.  They
work on    the currently selected (probably currently playing) module, and
their meanings should be obvious.

Add button

    This button    works basically    the same way as    the 'New' button on the
main window - it brings    up the file requester and allows you to    select
modules.  However, it doesn't cause the previous program to be cleared when
you finish, and    it doesn't start playing a new module immediately.  Under
1.3, you'll have to use this button to repeatedly bring up the file
requester in order to build programs.  However,    with the registered version
of MultiPlayer you only    have to    build a    program    once, save it, then tell
MultiPlayer to reload it whenever it starts up.     (Hint,    hint...)

Del button

    This button    deletes    the currently selected module in the program list.
If this    module is currently playing, the module    continues playing - it only
removes    the module from    the program, not immediately from memory.

Clear button

    Clears the entire current program list.  As    with the 'Del' button, it
does not stop any currently playing module.

Sort button

    Sorts the entire current program list alphabetically.  Handy if you
like to    use random play    (and thus don't really care about the play order)
but you'd like a nice neat module listing.

Load button

    Brings up the file requester so you    can load a previously saved program
from disk.  (This button will only work    on the registered version of
MultiPlayer.) The newly    loaded program will replace the    current    program.

    Note that you can also load    saved programs from the    regular    module
requester - programs are recognized just like modules, and programs
selected this way will automatically be    loaded and run.     (You could even
put the    name of    another    program    file at    the bottom of the first    one, and
chain programs together!)

Save button

    Brings up the file requester and lets you save the current program to a
disk file.  (Also only works on    the registered version.) You can then load
it again later through the Load    gadget or using    any method normally used to
select modules - the file requester, Workbench extended-select when
starting MultiPlayer, or CLI arguments.     (See the 'Startup' for    details    on
starting MultiPlayer.)

    If you want    to create or modify module program files yourself, just
take a look at one of the files    MultiPlayer generates -    it's just a simple
text file.  Lines starting with    'DIR' denote changes of    directory - all
filenames after    that until another 'DIR' keyword will be looked    for in that
directory.



                Preferences    Window
                ~~~~~~~~~~~~~~~~~~

    MultiPlayer's built-in Preferences window can be opened by clicking on
the 'Prefs' button in the main MultiPlayer window.  It contains    a few
options    (there will be more in future versions)    which you can use to tailor
MultiPlayer to your own    preferences.  The gadgets are described    below:

Play gadget

    Use    this to    select between sequenced play, random play, and    'over and
over' mode.  In sequenced play, the modules in the program list are played
one after another, from    beginning to end, in the order they appear in the
program    list.  In random play, a module    plays once and then another is
randomly selected.  In 'once' mode, the    song is    played only once, then is
unloaded and MultiPlayer becomes idle.    In 'over and over' mode, anything
you select is played forever until you tell MultiPlayer    to start a
different module.  (In these last two mode, you    can still use the 'Next'
and 'Prev' buttons in the main window to change    modules; MultiPlayer just
doesn't do it by itself.)

Show gadget

    This cycle gadget allows you to select the type of display you want    to
appear in the main window's title bar while a module is playing.  In clock
mode, a    clock appears displaying the amount of time this module    has been
playing    in minutes and seconds.     In sequence mode (this    has no relation    to
the sequence mode in the 'Play'    gadget), on NoiseTracker or similar
modules    that play sequences of blocks, the current sequence number and the
number of sequences in the song    is displayed.  (On modules that    don't
support    this, the clock    is displayed.) You can tell MultiPlayer    to display
the current sequence number either starting from 0 and ending at length-1,
as most    trackers display sequence numbers, or starting from 1 and ending
at (length), which is the more 'natural' way of    counting.  Selecting the
'Nothing' option in this gadget    will leave you with a simple, clean,
unadulterated title bar.

Save button

    Saves the current preferences to the disk file ENV:MultiPlayerPrefs, as
well as    to the same file in ENVARC:.  (With a preferences window as simple
as this, there's no real need for separate 'Save' and 'Save Default'
options.)

    The    preferences saved include, as well as the current settings of the
above two gadgets, the positions of the    three main MultiPlayer windows.    The
next time you run MultiPlayer, the windows will    pop up wherever    they were
when you saved the preferences.     Note that the position    of the main control
panel window can only be updated if the    window is currently in the "zoomed"
state when you save the    preferences, so    you can    see the    module information
and gadgets.  (This is due to a    slight deficiency in 2.0.)

OK button

    Does exactly the same thing    as the close gadget on the window does -
closes the Preferences window.    It does    NOT cause the new preferences to be
activated, because they    are activated the moment you select them.  (Isn't
multitasking wonderful?) There is no 'Cancel' gadget because I figure it's
not too    difficult to change back any buttons you accidentally hit, since
there are so few...



                Keyboard Shortcuts
                ~~~~~~~~~~~~~~~~~~

    Several keyboard shortcuts are available from any MultiPlayer window
(except    the file requester).  Most of these have been mentioned    before in
this document, but they    are listed all together    here.  All of these are
available under    1.3 as well as 2.0.  These keys    are listed below:

ESC key

    Terminates MultiPlayer immediately (a shortcut for the close gadget    on
the main window.

F1 key
Help key

    Opens the Program window, or closes    it if it is already open.

F2 key

    Opens the Preferences window, or closes it if it is    already    open.

Help key

    Under 2.0, brings up the module program window (a shortcut for the
'Program' button on the    main window).

Spacebar

    If a module    is currently playing, stops (or    pauses it) without
unloading, like    the 'Stop' button in the main window.  If a module is
loaded but NOT playing,    it continues or    restarts it, just like the 'Play'
button.

Delete key

    Unloads ('ejects') the currently loaded module.

Up/down    arrows

    These switch to the    previous or next modules in the    program    list,
respectively.  In random play, these simply select another module at
random.     (These    are shortcuts for the 'Next' and 'Prev'    buttons    in the main
window.)

Left/right arrows

    For    modules    that contain more than one song, these select the previous
or next    song, respectively (shortcuts for the 'Song' cycle gadget).



                  Startup Options
                  ~~~~~~~~~~~~~~~

    When starting MultiPlayer from Workbench (either 1.3 or 2.0), you can
extended-select    the icons of as    many modules as    you want when you start
MultiPlayer.  It will add all of these modules to the program and
immediately start playing the first one    (or a random selection,    if you have
selected random    play in    your saved preferences).

    If you're running Kickstart 1.3, MultiPlayer will accept a single
argument from the CLI (don't use quotes, even if there are spaces).  If
this argument ends in a    ':' or '/', MultiPlayer    will change to that
directory before displaying the    ARP file requester.  If    it doesn't end in
one of these characters, MultiPlayer will try to load the specified file as
a module and start it playing rather than displaying the file requester
immediately.

    If you're running Kickstart 2.0, MultiPlayer supports some extra
command-line options:

    DIR=DIRECTORY,MODULES/M,SCREEN/K,NOREQUEST/S,NOWINDOW/S,NOREXX/S

    (On    the unregistered version, the NOREXX option will not appear.)
Following is a description of these arguments:

DIRECTORY

    The    first argument on the command line (or any argument preceded by
this keyword) tells MultiPlayer    what directory to go to    the first time it
displays the file requester.  This is also where it will look for modules
you specify on the command line    (see below) if you don't specify full
pathnames for them.

MODULES/M

    The    second argument    (if you    don't explicitly use the DIRECTORY or
MODULES    keywords) begins a list    of modules to put into MultiPlayer's
program    list on    startup.  MultiPlayer imposes no limitations on    the number
of modules you can specify using this keyword, although    command    lines are
limited    to 256 characters.  After MultiPlayer starts up, instead of showing
the file requester immediately,    it will    load and begin playing the first
module in the program list (or a randomly selected module, if you have
selected random    playing).  With    the registered version of MultiPlayer, you
can specify a program file to load and start initially instead of a list of
modules.

SCREEN/K

    You    can use    this parameter to tell MultiPlayer to open its windows on a
screen other than the Workbench    (or default) screen.  Just supply the name
of the public screen as    this parameter,    and MultiPlayer    will try to use    it
for all    its windows.  The named    public screen must already be open.

NOREQUEST/S

    If you specify the switch, MultiPlayer will    not display the    file
requester immediately after it loads, even if you don't specify any modules
to start playing.  If you don't specify any modules, MultiPlayer will
simply sit idle    until you tell it to do    something.

NOWINDOW/S

    This switch    causes MultiPlayer to load and run without a window.  If
you specify modules to start playing, MultiPlayer will play them as usual,
but you    won't see any visual indication that MultiPlayer is running.  You
can still control the registered version of MultiPlayer    through    its ARexx
port, assuming you haven't turned that off as well.  Using this switch will
save about 5K of memory, since the part    of MultiPlayer that handles the
window interface is never loaded (and of course    the window itself is not
occupying memory).

NOREXX/S

    If you specify this    switch (which only exists on the registered
version), MultiPlayer will not open its    ARexx port.  Using this    switch will
save a little extra memory (not    much though - less than    1K) if you don't
need the ARexx port.

    If you specify both    NOREXX and NOWINDOW, you will effectively have no
way to control MultiPlayer apart from rebooting    - it will go on    playing
modules    as you instruct    it to at first,    and will not stop unless it
encounters a major error of some kind.    (If that happens, you basically
"lose" it for good.) I don't recommend doing this without a good reason.



                ARexx Port
                ~~~~~~~~~~

    If you have    ARexx, either as an independent    program    in 1.3 or as part
of the operating system    in 2.0+, you can use it    to control the registered
version    of MultiPlayer.     Whenever MultiPlayer is running, there    is an ARexx
port available called "RXTRACKER" which    you can    send various commands to.
MultiPlayer's ARexx port is designed to be (mostly) compatible with the
program    RxTracker by Dominic Giampaolo.     In addition, it has several
extended features, and of course you can use it    to play    all the    different
kinds of modules MultiPlayer understands.

    If MultiPlayer runs    into an    error when trying to load or play a module,
it generally returns an    error code of 10.  When    any error occurs, a pointer
to a descriptive error string is saved and you can get it with the
LASTERROR command to display for the user.

    A listing of the ARexx commands MultiPlayer    understands follows:

LOAD    <filename>

    Loads a module into    memory from disk.  It is generally a good idea to
supply a complete pathname, since MultiPlayer looks for    the module starting
at whatever directory the file requester last happened to be looking at.
This command does not start the    module playing.     If you    want to    start
playing    immediately, you don't have to use this command at all - you can
simply supply a    filename on the    PLAY command and it will load and start
playing    immediately.  Note that    unless you tell    MultiPlayer to load a
program    file, this command won't affect the program list at all - the ARexx
port in    general    operates independently of the standard user interface.    If
you explicitly tell MultiPlayer    to load    a program file using this command,
then the new program list will replace the old one.

PLAY    [<filename>] [<songnumber>]

    Starts playing a module.  If you supply the    filename, MultiPlayer stops
any module currently playing and tries to load the specified module from
disk, like the LOAD command.  If you don't supply the filename, MultiPlayer
plays (or re-plays from    the start) an already-loaded module.  (If no module
is loaded and you don't specify a filename, MultiPlayer returns error code
5 and otherwise    does nothing.) For modules with    more than one song, you    can
supply the song    number to play.     Songs are numbered starting at    zero.  If
you don't supply a song number, the first one (song zero) is assumed.

STOP

    Stops playing any module that is currently playing without unloading
the module.  You can then restart it later with    PLAY or    CONTINUE.

UNLOAD

    Stops and unloads any currently loaded module.

CONTINUE

    Tries to restart a stopped module at the position it was at    before the
STOP command was given.     If the    module has never been started, it simply
starts from the    beginning.  If the module was already playing, it does
nothing.  If the module    type doesn't support restarting, MultiPlayer
returns    error code 5 and does NOT start    the module - you can then use PLAY
to start again from the    beginning if you want, or else chew out    the user
for using weird    module formats.

OPENWINDOW

    Opens the main MultiPlayer window.    It will    be opened in the small
title-bar zoom state, and none of MultiPlayer's other windows will be
opened with it.     If the    window was already open, this command does nothing.
It returns an error if the window can't be opened.  Remember that while the
window is open the user    can use    it to change modules and such, possibly
messing    up your    perfectly organized and    timed ARexx-controlled playing
sequences.

CLOSEWINDOW

    Closes the MultiPlayer window, if it was open.  MultiPlayer    remains
active,    but impervious to user interface (through Intuition anyway).  Now
only ARexx commands can    affect MultiPlayer.

LASTERROR

    Returns an error message describing    the last error that occurred that
had to do with the ARexx port.    (Errors    that the user causes by
manipulating the window    do not affect this.) You'll have to have 'options
results' turned on for this to work, and the error will appear in the
'RESULT' variable.

QUIT

    Causes MultiPlayer to terminate immediately.



                 Messages
                 ~~~~~~~~

    This section lists most of the error or warning messages MultiPlayer
can produce.  Look here    if you have trouble deciphering    the meaning of one.

"Not enough chip memory"

    Tracker-style modules generally must be loaded into    one big    continuous
chunk of chip memory.  Therefore, even if the Workbench    (or some other
program) says you have enough memory, it may not have one big enough chunk.
Close some windows, exit some programs.     If all    else fails, reboot and try
fresh.

"Not enough memory"

    You    really are getting low.     MultiPlayer doesn't normally need too much
non-chip memory, since modules are always loaded into chip memory.  If you
get this message, it means you don't have much memory of ANY kind
available.  Better free    up something quick.

"Required memory occupied"

    You    will only get this message from    non-relocatable    AMOD or    GMOD
modules.  It means that    the module has a specific address it must be loaded
into, but part or all of the required block of memory is already in use.
Free up    as much    memory as possible and try again.  If most of your memory
is free    and you    still can't load it, chances are there's some little
allocated fragment that    some program has forgotten about that's still
sitting    in the required    area.  Your best bet is    to reboot and try on a
fresh system.  If you have more    than 512K of chip memory, try running my
program    'ChipMunch' (included with MultiPlayer)    just after you reboot to
keep programs out of the commonly used areas.

"Nothing selected"

    Not    an error, this simply means that you pressed Cancel in the file
requester without selecting any    modules.  MultiPlayer then happily goes    on
doing whatever it was already doing.

"Unknown module type"

    MultiPlayer    doesn't recognize the file you selected as one of the
module types it    knows.    Either this isn't a music module, or it's one that
it doesn't know how to handle.  If it is a music module that MultiPlayer
doesn't know about, send me the module and player/interface code, and it
should make it into the    next version of    MultiPlayer.

"Corrupt module"

    MultiPlayer    recognized the module, but it didn't look right for some
reason.     Maybe it's a module written with an incompatible version of the
music program, or maybe    the module itself got munched somehow.

"Error playing module"

    A general catch-all.  This error usually is    displayed as a result of
error reports from initialization routines of individual players.  It
generally means    that the module    loaded fine, but the player had    trouble
playing    it.  Sometimes it means    the same thing as "Corrupt module", or it
might mean that    the player ran out of memory but was too stupid    to tell
MultiPlayer about it specifically.

"Can't load module"

    The    requested file was not found, or there was a disk error    while
reading    it.  If    you get    this message after selecting a file from the file
requester, chances are the disk    is corrupt (in this case AmigaDOS should
have already given you a requester saying so), or the file may be open for
writing    from some other    program.

"Directory not found"

    Somehow you    managed    to tell    MultiPlayer to load something from a
directory that doesn't exist.  Maybe you moved the directory somewhere
else, or forgot    an Assign somewhere.  This usually only    happens    with ARexx
commands or loaded program lists.

"Audio hardware in use"

    MultiPlayer    can't allocate the audio hardware through the audio.device.
This probably means that some other music editor or player is currently
running.  Find the culprit program and close it.  If all else fails, reboot
and try    again.

"No CIAB timers available"

    MultiPlayer    generally uses one of the two timers on    CIA (Complex
Interface Adapter) B for timing    its music.  However, other programs like to
use these also.     In particular,    (I believe) one    of the timers may be in    use
if the serial port is in operation.  Other than    that, music programs are
generally the biggest consumers    of CIAB    timers.     Make sure no other music
player or composer programs are    running, and try closing terminal programs
or other programs that use the serial port.

"Please decompress this module"

    It is unlikely that    you will ever get this message,    but if you do, it
means that (a) the module MultiPlayer is trying    to load    is compressed
somehow    (MultiPlayer had to use    the xpkmaster.library to decompress it),
and (b)    it is an AMOD or GMOD module that must load at an absolute address,
and (c)    MultiPlayer would have to re-load the module rather than just
copying    it to its final    position because the memory the    module occupied
initally overlapped the    required module    address.  If you don't quite
follow,    don't sweat - just decompress the module.



                 Supported Formats
                 ~~~~~~~~~~~~~~~~~

MultiPlayer currently supports the following module types:

    15-instrument SoundTracker modules (most anyway)
    31-instrument SoundTracker V2.3-2.5/NoiseTracker V1.0-1.3D modules

    NoiseTracker 1.3D packed modules (with or without the embedded player)

    StarTrekker 1.2    AM/FM modules (Extra '.NT' file    required)

    MED 3.xx modules (MMD0 modules only - not "Song&Samples" files)
        (no 2.xx modules anymore - use MED 3.xx    to convert them!)

    SoundFX    V1.3 executable    modules    (Player    V2.2)
        (Will probably ONLY work with this version, since it does
        some run-time patching to get it to play under MultiPlayer.)

    Old Future Composer 'SMOD' modules (what version is this specifically???)
    Future Composer    1.4 ('FC14') modules

    JamCrackerPro 1.0a modules

    SoundMonitor 2.0 modules

    Dave Whittaker modules
        (Be careful - these aren't completely system friendly...)

    Delta Music modules (two versions)

    Oktalyzer V1.1 4-channel modules (untested)

    SidMon modules (untested)

    Mark II    modules    (untested)

    Generic    embedded-player    modules    that start with    something like
            jmp init(pc)
            jmp music(pc)
            jmp end(pc)
        (Such as NoiseTracker 1.3 packed w/player modules)

    AudioMaster III    sequenced 8SVX sounds (mono only)

    'XMOD',    'AMOD',    and 'GMOD' formats described in    'Formats.doc'

    Some of the    module types are marked    as 'untested'.    This means exactly
what it    says - I found out the appropriate methods to play these and easily
added support into MultiPlayer,    but I didn't have any modules to test it
on.  So    if I made a stupid mistake, one    or more    of these may not work at
all.  If you try one of    these formats and it doesn't work, send me a few
modules    in the appropriate format to test with,    and if you're the first to
do so, I'll register you for free and send you the new bug-fixed version of
MultiPlayer.

    Although sequenced 8SVX sounds are technically only    sampled    sound
files, they have some music capability and look    promising.  Besides, the
player also plays non-sequenced    8SVX sounds, so    you can    also play your
movie clips and    such with MultiPlayer.    (I'm not sure if AudioMaster III is
the only program that currently    supports sequenced 8SVX    files, but it's the
only one I've seen so far.) Stereo is currently not supported - sorry, I'll
get to that eventually.



                  History
                  ~~~~~~~

1.11a    (12-Dec-91)
    Fixed bug in 8SVX player.
    Window positions are now saved with preferences.

1.11    (10-Dec-91)
    Repeat detection bug in    ST/NT player fixed.
    Program    and preferences    windows    now save their positions while closed.
    Enhanced author    name detection.
    Added middle-mouse-button zoom feature.
    Added 'Nothing'    option to the show mode    in preferences.
    Improved Delta Music module recognition.

1.10    (18-Nov-91)
    Right mouse button in the main window has changed functions:
        Under 1.3, it zooms the    window (since there's no zoom gadget)
        Under 2.0, it shows the    program    window (like the Help or F1 key)
    File requester is now asynchronous (other windows remain active).
    Control    panels are now fully 1.3 compatible.
        (Although they still don't look as nice as in 2.0...)
    Keyboard shortcuts now supported in all    control    panels.
    Added public screen support.
    Added "play once" feature.
    DMA delays now use scanline waits instead of delay loops.
    Re-opening sub windows now closes them rather than bringing them to the    front.
    Added AppWindow    support    for 2.0.

1.01    (8-Nov-91)
    Added 'Sort' button in program window.
    Fixed a    serious    bug in GMOD player.  (Only serious if you have GMOD modules...)
    Enhanced author    name recognition for ST/NT modules.

1.00    (5-Nov-91)
    This is    basically a rewrite of most of the program.
        (I'm not listing all the additions - there are way too many.)
    Major changes and additions to Formats.doc.
    Music no longer    cuts off when file requester is    displayed.
    Removed    built-in code compression.  (Maybe I'll put it back in later.)
    Audio device now allocated while playing music.
    Fixed SoundFX player bug which caused crashing on advanced processors.
    Players    now use    longer DMA delays (normally 300) only on fast processors.
        (Wouldn't want to bog down you poor ol'    68000 users would we?)
    Major rewrite of player    selection code.
    CIAB interrupts    now defer to software interrupts to avoid hogging
        CPU time in a high-priority interrupt.

0.95A    (6-Sep-91)
    Fixed bug where    song position appeared when no module was playing.
    Fixed ST/NT player bug for modules with    negative song repeat positions.

0.95    (27-Jul-91)
    Added song position indicator for ST/NT    and MED    modules.
    Added code to turn low-pass filter off by default (will    soon be    selectable).
    Added Messages section to the documentation.
    Fixed window position so it snuggles right up next to the screen gadgets.

0.94A    (26-Jul-91)
    Fixed player window height on pre-2.0 operating    systems.
    Increased delay    loop (ugh!) in NoiseTracker player for faster processors.
    Fixed song repeat bug in NoiseTracker player.
    Hacked NoiseTracker player to play old 15-instrument modules.
    Fixed memory trashing bug in NoiseTracker player.
        (I hate    cleaning up someone else's code!)

0.94    (23-Jul-91)
    Uses one of the    CIAB timers for    timing rather than the VBlank interrupt.
    Finally    uses Workbench 2.0 ASL file requester if available.
    Added MED 3.xx modules,    removed    MED 2.xx songs.

0.93    (3-Jul-91)
    Workbench 2.0 compatible (although some    modules    may not    be).

0.92    (7-Jun-91)
    Added 'AMOD' absolute loading module format described in 'Formats.doc'.
    Added 'GMOD' general module format described in    'Formats.doc'.
    Added NoiseTracker 1.3D    packed (with player) modules.
    Added StarTrekker 1.2 AM synthesized modules.
    Updated    the SoundTracker/NoiseTracker player.
        (New player comes from NoiseTracker 1.3D)

0.91    (29-Apr-91)
    Added 'XMOD' format described in 'Formats.doc'.
    Removed    "unknown" module formats (turned those modules into XMOD's)

0.90    (27-Apr-91)
    First preliminary release.  Nothing fantastic.



                   Registration
                   ~~~~~~~~~~~~

    MultiPlayer    is Shareware.  Although    I detest the fact that humans must
prove their worth to society through a meaningless medium known    as money,
today's society requires it - without money you don't eat, and you don't
buy Amigas. Therefore, for $15 or more you will    get the    registered version
of MultiPlayer which allows loading and    saving of programs (module lists),
as well    as the full-featured ARexx port    described later    in this    document
(useful    for playing modules with AmigaVision and the like).  Of    course,    you
also gain my favor - suggestions for improvements will be taken    much more
seriously from registered users.

    I'm planning to release the source code to MultiPlayer.  However, it
uses many of my    library    routines that I    have not released yet (though I'm
planning to when I have    the chance), so    it will    have to    wait a while. The
source code will probably be available with a $30 registration fee (or an
additional $15 for users who have already paid the $15 registration fee).
How hard I work    on getting my library routines cleaned up and released,    and
therefore how soon I get MultiPlayer's source code released, depends a
great deal on how much support I get for MultiPlayer.



                  Contact Address
                  ~~~~~~~~~~~~~~~

    I tend to move around a great deal,    so mail    sent directly to me
sometimes has a    hard time catching up.    If you want mail to reach me (it
may take a while, but it WILL reach me), send it to this address:

    Bryan Ford
    8749 Alta Hills    Circle
    Sandy, UT 84093

    I can be reached more quickly (for the time    being anyway) on the phone
or through one of the electronic mail addresses    below:

    [phone]
    [e-mail]
    [e-mail]
    [e-mail]

    If you want    to get something to me through the mail    more quickly, FIRST
call or    E-mail me to make sure I'm still here, then send it to this
address:

    Bryan Ford
    27104 Ballif Hall
    University of Utah
    Salt Lake City,    UT 84112